The Shared C Library for GCCSDK GCC usage [libscl]
=========================================

This directory contains the necessary header files and source files to
enable GCCSDK GCC built programs to use the SharedCLibrary module.

This library is Copyright (c) 1995-2005 Nick Burrett
                Copyright (c) 2005-2007 UnixLib Developers

libscl is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


History
-------

Originally the major part of libscl was called !Clib and distributed as a
separate RISC OS application/distribution.  Over the years this became part
of GCCSDK to allow GCC built programs to use the SharedCLibrary module in
RISC OS as runtime library and alternative for UnixLib.


Using the SharedCLibrary library
--------------------------------

For general use, all that is needed is an extra command line option to GCC:
  -mlibscl

The following commands will compile the file c.hellow:
  *gcc -c hellow.c -O2 -mlibscl
  *gcc -o hellow hellow.o -mlibscl


Filename translation for the Shared C Library
---------------------------------------------

The Shared C Library does not benefit from UnixLib's filename translation
code by default.  However, defining the symbol __RISCOSIFY before you include
stdio.h will cause remove(), rename(), fopen() and freopen() to use the UnixLib
filename translation code on the filenames supplied as arguments to those
functions.

See the GCC and UnixLib documentation for instructions on how to use the
filename translation code, especially the fancy options.


Known problems
--------------

1. The filename translation code

If you use command-line redirection of stdin and stdout, the filenames used
for redirection are not translated. If this is important, use UnixLib.

2. C++

libscl usage by C++ programs is currently not supported in GCCSDK 4 (it was
in GCCSDK 3.4).

3. float argument passing in va_args structure

-EOF-
